Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

SGSetChannelBounds

The SGSetChannelBounds function allows the sequence grabber component to specify your channel's display boundary rectangle.

pascal ComponentResult SGSetChannelBounds (SGChannel c,
                                          const Rect *bounds);


c

Identifies the channel connection for this operation.

bounds

Contains a pointer to a rectangle that defines your channel's display boundary rectangle.

SGGetChannelBounds

The SGGetChannelBounds function allows the sequence grabber component to determine your channel's display boundary rectangle.

pascal ComponentResult SGGetChannelBounds (SGChannel c,
                                         Rect *bounds);


c

Identifies the channel connection for this operation.

bounds

Contains a pointer to a rectangle structure that is to receive information about your channel's display boundary rectangle.

SGGetSrcVideoBounds

The SGGetSrcVideoBounds function allows the sequence grabber component to determine the size of the source video boundary rectangle.

pascal ComponentResult SGGetSrcVideoBounds (SGChannel c, Rect *r);


c

Identifies the channel connection for this operation.

r

Contains a pointer to a rectangle structure that is to receive information about your channel's source video boundary rectangle.

SGSetVideoRect

The SGSetVideoRect function allows the sequence grabber component to specify a part of the source video image that is to be captured by your channel component.

pascal ComponentResult SGSetVideoRect
                                         (SGChannel c, const Rect *r);


c

Identifies the channel connection for this operation.

r

Contains a pointer to the dimensions of the rectangle that defines the portion of the source video image to be captured. This rectangle must lie within the boundaries of the source video boundary rectangle, which the sequence grabber can obtain by calling the SGGetSrcVideoBounds function, described in the previous section.

SGGetVideoRect

The SGGetVideoRect function allows the sequence grabber to determine the portion of the source video image that your component is going to capture.

pascal ComponentResult SGGetVideoRect (SGChannel c, Rect *r);


c

Contains a pointer to the channel connection for this operation.

r

Contains a pointer to a rectangle structure that is to receive the dimensions of the rectangle that defines the portion of the source video image your component is going to capture.

SGSetVideoCompressorType

The SGSetVideoCompressorType function allows the sequence grabber component to specify the type of image compression your component is to apply to the captured video images.

pascal ComponentResult SGSetVideoCompressorType (SGChannel c,
                                         OSType compressorType);


c

Identifies the channel connection for this operation.

compressorType

Specifies the type of image compression to use. The value of this parameter must correspond to one of the image compressor types supported by the Image Compression Manager. Currently, six CodecType values are provided by Apple. You should use the GetCodecNameList function to retrieve these names, so that your application can take advantage of new compressor types that may be added in the future. For each CodecType value in the following list, the corresponding compression method is also identified by its text string name.

	Compressor type	Compressor name
	'rpza'	video compressor
	'jpeg'	photo compressor
	'rle '	animation compressor
	'raw '	raw compressor
	'smc '	graphics compressor
	'cvid'	compact video compressor

See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information about valid compressor types. If this value is set to 0, its default compression type is selected.

SGGetVideoCompressorType

The SGGetVideoCompressorType function allows the sequence grabber component to determine the type of image compression that is being applied to your channel's video data.

pascal ComponentResult SGGetVideoCompressorType (SGChannel c,
                                         OSType *compressorType);


c

Identifies the channel connection for this operation.

compressorType

Contains a pointer to an OSType field that is to receive information about the type of image compression to use. Return a value that corresponds to one of the image-compression types supported by the Image Compression Manager. Currently, six CodecType values are provided by Apple. You should use the GetCodecNameList function to retrieve these names, so that your application can take advantage of new compressor types that may be added in the future. For each CodecType value in the following list, the corresponding compression method is also identified by its text string name.

	Compressor type	Compressor name
	'rpza'	video compressor
	'jpeg'	photo compressor
	'rle '	animation compressor
	'raw '	raw compressor
	'smc '	graphics compressor
	'cvid '	compact video compressor

See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information about valid compressor types. If this value is set to 0, its default compression type is selected.

SGSetVideoCompressor

The SGSetVideoCompressor function allows the sequence grabber component to specify many of the parameters that control image compression of the video data captured by your video channel.

pascal ComponentResult SGSetVideoCompressor (SGChannel c,
                                         short depth,
                                         CompressorComponent compressor,
                                         CodecQ spatialQuality,
                                         CodecQ temporalQuality,
                                         long keyFrameRate);


c

Identifies the channel connection for this operation.

depth

Specifies the depth at which the image is likely to be viewed. Image compressors may use this as an indication of the color or grayscale resolution of the compressed images. If the sequence grabber component sets this parameter to 0, let the sequence grabber component determine the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 33, 34, 36, and 40 indicate 1-bit, 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your component can determine which depths are supported by a given compressor by examining the compression information record (defined by the CodecInfo data type) returned by the Image Compression Manager's GetCodecInfo function (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information on the GetCodecInfo function).

compressor

Specifies the image compressor identifier. The sequence grabber component may specify a particular compressor by setting this parameter to its compressor identifier. You can obtain these identifiers from the Image Compression Manager's GetCodecNameList function.

spatialQuality

Specifies the desired quality of the compressed image. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values.

temporalQuality

Specifies the desired temporal quality of the sequence. This parameter governs the level of compression the sequence grabber component desires with respect to information in successive frames in the sequence. The sequence grabber component sets this parameter to 0 to prevent the image compressor from applying temporal compression to the sequence. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for other valid values.

keyFrameRate

Specifies the maximum number of frames allowed between key frames. Key frames provide points from which a temporally compressed sequence may be decompressed. The sequence grabber component uses this parameter to control the frequency with which the image compressor places key frames into the compressed sequence. For more information about key frames, see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime .

The compressor determines the optimum placement for key frames based upon the amount of redundancy between adjacent images in the sequence. Consequently, the compressor may insert key frames more frequently than you have requested. However, the compressor will never place key frames less often than is indicated by the setting of the keyFrameRate parameter. The compressor ignores this parameter if you have not requested temporal compression (that is, you have set the temporalQuality parameter to 0).

SGGetVideoCompressor

The SGGetVideoCompressor function allows the sequence grabber component to determine your channel's current image-compression parameters.

pascal ComponentResult SGGetVideoCompressor (SGChannel c,
                                         short *depth,
                                         CompressorComponent *compressor,
                                         CodecQ *spatialQuality,
                                         CodecQ *temporalQuality,
                                         long *keyFrameRate);


c

Identifies the channel connection for this operation.

depth

Contains a pointer to a field that is to receive the depth at which the image is likely to be viewed. Image compressor components may use the depth as an indication of the color or grayscale resolution of the compressed images. Return the depth value currently in use by your channel component. If this parameter is set to nil , the sequence grabber component is not interested in this information.

compressor

Contains a pointer to a field that is to receive an image compressor identifier. Return the identifier that corresponds to the image compressor your channel is using. If this parameter is set to nil , the sequence grabber component is not interested in this information.

spatialQuality

Contains a pointer to a field that is to receive the desired compressed image quality. Return the current quality value. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values. If this parameter is set to nil , the sequence grabber component is not interested in this information.

temporalQuality

Contains a pointer to a field that is to receive the desired temporal quality of the sequence. This parameter governs the level of compression you desire with respect to information between successive frames in the sequence. Return the current temporal quality value. If this parameter is set to nil , the sequence grabber component is not interested in this information.

keyFrameRate

Contains a pointer to a field that is to receive the maximum number of frames allowed between key frames. Key frames provide points from which a temporally compressed sequence may be decompressed. This value controls the frequency at which the image compressor places key frames into the compressed sequence. Return the current key frame rate. If this parameter is set to nil , the sequence grabber component is not interested in this information.

SGSetVideoDigitizerComponent

The SGSetVideoDigitizerComponent function allows the sequence grabber component to assign a video digitizer component to your video channel.

pascal ComponentResult SGSetVideoDigitizerComponent
                                         (SGChannel c, ComponentInstance vdig);


c

Identifies the channel connection for this operation.

vdig

Contains a component instance that identifies a connection to a video digitizer component. Your video channel component should use this video digitizer component to obtain its source video data.

SGGetVideoDigitizerComponent

The SGGetVideoDigitizerComponent function allows the sequence grabber component to determine the video digitizer component that is providing source video to your video channel component. For example, the sequence grabber component can use this function to obtain access to the video digitizer component so that the grabber component can set the digitizer's parameters. See the chapter "Video Digitizer Components" in this book for information about video digitizer components.

pascal ComponentInstance SGGetVideoDigitizerComponent
                                         (SGChannel c);


c

Identifies the channel connection for this operation.

SGVideoDigitizerChanged

The SGVideoDigitizerChanged function allows the sequence grabber component to notify your component whenever an application changes the configuration of your video channel's video digitizer.

pascal ComponentResult SGVideoDigitizerChanged (SGChannel c);


c

Identifies the channel connection for this operation.

SGSetCompressBuffer

Some video source data may contain unacceptable levels of visual noise or artifacts. One technique for removing this noise is to capture the image and then reduce it in size. During the size reduction process, the noise can be filtered out.

The SGSetCompressBuffer function allows the sequence grabber component to direct your component to create a filter buffer for your video channel. Logically, this buffer sits between the source video buffer and the destination rectangle that the sequence grabber component sets with the SGSetChannelBounds function, described on SGSetChannelBounds . The filter buffer should be larger than the area enclosed by the destination rectangle.

pascal ComponentResult SGSetCompressBuffer (SGChannel c,
                                         short depth,
                                         const Rect *compressSize);


c

Identifies the channel connection for this operation.

depth

Specifies the pixel depth of the filter buffer. If the sequence grabber sets this parameter to 0, use the depth of the video buffer (which the sequence grabber sets with the SGSetChannelBounds function).

compressSize

Contains a pointer to the dimensions of the filter buffer. This buffer should be larger than the destination buffer. The sequence grabber component sets this parameter to nil , or it sets the coordinates of this rectangle to 0 (specifying an empty rectangle), to stop filtering the input source video data.

SGGetCompressBuffer

The SGGetCompressBuffer function returns information about the filter buffer that the sequence grabber component has established for your video channel.

pascal ComponentResult SGGetCompressBuffer (SGChannel c,
                                         short *depth,
                                         Rect *compressSize);


c

Identifies the channel connection for this operation.

depth

Contains a pointer to a field that is to receive the pixel depth of the filter buffer. If your component is not filtering the input video data, set the returned value to 0.

compressSize

Contains a pointer to a rectangle structure that is to receive the dimensions of the filter buffer. If your component is not filtering the input video data, return an empty rectangle (all coordinates set to 0).

SGSetFrameRate

The SGSetFrameRate function allows the sequence grabber to specify a video channel's frame rate for recording.

pascal ComponentResult SGSetFrameRate (SGChannel c,
                                          Fixed frameRate);


c

Identifies the channel connection for this operation.

frameRate

Specifies the desired frame rate. If this parameter is set to 0, use your channel's default frame rate. Typically, this corresponds to the fastest rate that your channel can support.

SGGetFrameRate

The SGGetFrameRate function allows you to retrieve a video channel's frame rate for recording.

pascal ComponentResult SGGetFrameRate (SGChannel c,
                                         Fixed *frameRate);


c

Identifies the channel connection for this operation.

frameRate

Contains a pointer to a field to receive the current frame rate. Return your channel's current frame rate.

SGSetUseScreenBuffer

The SGSetUseScreenBuffer function allows the sequence grabber to control whether your video channel uses an offscreen buffer.

pascal ComponentResult SGSetUseScreenBuffer (SGChannel c,
                                         Boolean useScreenBuffer);


c

Identifies the channel connection for this operation.

useScreenBuffer

Indicates whether to use an offscreen buffer. If this parameter is set to true , draw directly to the screen. If it is set to false , your channel may use an offscreen buffer. If your channel cannot work with offscreen buffers, ignore this parameter.

SGGetUseScreenBuffer

The SGGetUseScreenBuffer function allows the sequence grabber to determine whether your video channel is allowed to use an offscreen buffer.

pascal ComponentResult SGGetUseScreenBuffer (SGChannel c,
                                         Boolean *useScreenBuffer);


c

Identifies the channel connection for this operation.

useScreenBuffer

Contains a pointer to a Boolean value. Set this field to true if your channel draws directly to the screen. Set it to false if your channel can use an offscreen buffer. If your channel cannot work with offscreen buffers, ignore this value.

SGAlignChannelRect

The sequence grabber calls your SGAlignChannelRect function in order to determine whether your channel prefers to draw at a particular screen location.

pascal ComponentResult SGAlignChannelRect (SGChannel c, Rect *r);


c

Identifies the connection to your channel.

r

Contains a pointer to a rectangle. On entry, this rectangle contains coordinates at which the sequence grabber would like to draw your captured video image. If your component can draw more efficiently or at a higher frame rate at a different location, update the contents of this rectangle to reflect where you would prefer to draw. The rectangle will be passed in with global, not local, coordinates.